---
title: Univer Sheets API
---

Univer Sheets 提供专业级电子表格能力，相关概念会尽可能与 Microsoft Excel 保持一致。

## 工作簿 Workbook

一个工作簿里包含多个工作表，可以看作是一个 Excel 文件。

`unitId` 可用作工作簿的唯一标识。

### 创建工作簿

[`univerAPI.createWorkbook(data, options)`](https://reference.univer.ai/zh-CN/classes/FUniver#createworkbook) 方法会创建并返回 `FWorkbook` 实例。

[`IWorkbookData`](/guides/sheets/model/workbook-data) 是一个对象，包含了工作簿的配置信息。

```typescript
const fWorkbook = univerAPI.createWorkbook({ id: 'Sheet1', name: 'Sheet1' })
console.log(fWorkbook)
```

您可以设置一个选项，使添加的工作簿不成为活动工作簿

```typescript
const fWorkbook = univerAPI.createWorkbook({ id: 'Sheet1', name: 'Sheet1' }, { makeCurrent: false })
console.log(fWorkbook)

// 3s 后如果想切换到此工作簿
setTimeout(() => {
  univerAPI.setCurrent(fWorkbook.getId())
}, 3000)
```

### 获取工作簿数据 [#get-workbook-data]

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const snapshot = fWorkbook.save()
console.log(snapshot)
```

### 销毁工作簿

当我们不再需要工作簿时，可以调用 `FUniver` 的 `disposeUnit` 方法来销毁实例。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const unitId = fWorkbook?.getId()
if (unitId) {
  univerAPI.disposeUnit(unitId)
}
```

<Callout type="warning">
  当 Univer 实例挂载的整个页面被销毁或路由被卸载时，务必调用 `univer.dispose()` 方法进行清理，而不是使用 `univerAPI.disposeUnit`。
  此外，`univer` 和 `univerAPI` 是两个不同的实例，关于如何获取它们的实例，请参考 [安装和基本使用](/guides/sheets/getting-started/installation)。
</Callout>

### 获取工作簿 ID

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook?.getId()
```

## 工作表 Worksheet

工作表中存储着表格数据，工作表属于工作薄，

一个工作薄可以包含多个工作表，同一个工作薄中工作表的名称不能重复。

`subUnitId` 可用作在工作薄中工作表的唯一标识。

### 获取工作表

获取工作薄中所有工作表

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const sheets = fWorkbook.getSheets()
```

获取工作薄中当前激活的工作表

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
```

### 获取工作表数据

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const sheetSnapshot = fWorksheet.getSheet().getSnapshot()
```

### 创建工作表 [#create-worksheet]

下面例子展示通过 [`FWorkbook.create`](https://reference.univer.ai/zh-CN/classes/FWorkbook#create) 方法创建一个工作表。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()

// 创建一个名为 'Sheet2' 的工作表，包含 10 行和 10 列
const newSheet = fWorkbook.create('Sheet2', 10, 10)
```

### 删除工作表

通过传入工作表实例或工作表 ID 来删除工作表

```typescript
// 删除第二个工作表
const fWorkbook = univerAPI.getActiveWorkbook()
const sheet = fWorkbook.getSheets()[1]
fWorkbook.deleteSheet(sheet)

// 下面的代码通过 id 删除指定的工作表
// fWorkbook.deleteSheet(sheet.getSheetId());
```

### 激活工作表

通过传入工作表实例或工作表 ID 来激活工作表, 或者通过 `FWorksheet.activate()` 方法激活工作表

```typescript
// 激活第二个工作表
const fWorkbook = univerAPI.getActiveWorkbook()
const sheet = fWorkbook.getSheets()[1]
fWorkbook.setActiveSheet(sheet)

// 通过 id 激活指定的工作表
// fWorkbook.setActiveSheet(sheet.getSheetId());

// 通过 FWorksheet.activate() 方法激活工作表
// sheet.activate();
```

### 获取工作表 ID

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
fWorksheet?.getSheetId()
```

### 刷新工作表

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
fWorksheet.refreshCanvas()
```

### 工作表缩放

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 200% 设置缩放比例为 200%
fWorksheet.zoom(2)
const zoomRatio = fWorksheet.getZoom()
```

### 滚动到指定位置

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 滚动到 D10 单元格
const fRange = fWorksheet.getRange('D10')
const row = fRange.getRow()
const column = fRange.getColumn()
fWorksheet.scrollToCell(row, column)

// 获取滚动状态
const scrollState = fWorksheet.getScrollState()
const { offsetX, offsetY, sheetViewStartColumn, sheetViewStartRow } = scrollState
console.log(scrollState) // sheetViewStartRow: 9, sheetViewStartColumn: 3, offsetX: 0, offsetY: 0
```

## 核心功能

### 权限控制

参考：[权限控制](/guides/sheets/features/core/permission)

### 公式

参考：[公式](/guides/sheets/features/core/formula)

### 行列操作

参考：[行列操作](/guides/sheets/features/core/row-col)

### 范围 Range

参考：[范围 Range](/guides/sheets/features/core/range-selection#range)

### 选区 Selection

参考：[选区 Selection](/guides/sheets/features/core/range-selection#selection)

### 单元格 Cell

参考：[单元格 Cell](/guides/sheets/features/core/range-selection#cell)

### 冻结

参考：[冻结](/guides/sheets/features/core/freeze)

### 集成自定义组件

参考：[集成自定义组件](/guides/sheets/ui/components)

## 参考

更多 API 请查看：

- [FWorkbook](https://reference.univer.ai/zh-CN/classes/FWorkbook)
- [FWorksheet](https://reference.univer.ai/zh-CN/classes/FWorksheet)
